﻿<?xml version="1.0" encoding="utf-8" ?>
<vAddin>
  <!--
    Yes, the root node is called vAddin.
  -->
  
  <Name>Example</Name>
  <!--
    This is the name of the vAddin used by vAddins to identify it.
    Can contain other tags, according to the host.
    It is used by the vAddins Packager and the compiler/builder.
    Can also be used by the host.
  -->

  <Version>1.2.3.4</Version>
  <!--
    This is the version of the add-in.
    Must be a valid System.Version as a string.
      Else, it will throw a format exception.
    Cannot contain other tags.
    It is used by the vAddins Packager and by the compiler/builder to determine whether the add-in needs recompilation.
    Can also be used by the host.
  -->

  <Description>This is an example vAddin XML manifest file.</Description>
  <!--
    This tag is optional.
    Can contain other tags, according to the host.
    It is supposed to contain the description of the add-in.
    It may be used by the vAddins Packager (the installer, more precisely).
    Can also be used by the host.
  -->

  <Author>Someone</Author>
  <!--
    This tag is optional.
    Can contain other tags, according to the host.
    It contains the name of the author(s).
    It may be used by the vAddins Packager (the installer, more precisely).
    Can also be used by the host.
  -->

  <References>
    <!--
      This node is optional and shall be used only if the add-in needs to target specific libraries.
      There are strict rules for this node.
      You may use only the nodes you see below and their associated attributes/content.
    -->
    
    <SystemReference path="System" />
    <SystemReference path="System.Windows.Forms.dll" />
    <!--
			The system reference targets a .NET assembly, like System.dll or System.Windows.Forms.dll
			The extension (".dll") is optional.
		-->

    <KnownReference path="Helper.dll" />
    <!--
			A known reference targets an assembly inside the addin's folder.
			A must-have for addins that use other assemblies.
      This also helps hiding source code.
		-->

		<AbsoluteReference path="C:\Just an assembly.dll" />
    <!--
			This kind of reference targets an absolute path in the filesystem.
			I personally can't imagine any real use for these but I added them anyway, just to be there.
      It's left her because... well... It's possible. All references are transformed into absolute file paths, anyway.
		--> 

    <HostReference path="Core" />
	  <!-- 
		  A host reference is a reference to a predefined assembly in the host application.
		  The "path" part is used by vAddins to identify which is the actual reference...
			When the host app passes references to vAddins they are attached to an ID (path) to identify them.
      
			In this example, "Core" is supposed to be the ID of the host's core assembly.
		-->
  </References>

  <Requirements>
    <!--
      This node is optional and shall be used only if the add-in requires certain conditions.
      There are strict rules for this node.
      You may use only the nodes you see below and their associated attributes/content.
    -->

    <AddinRequirement name="A Fictional Example">
      <Rule version="1.1.0.123" relation="==" />
      <Rule range="1.2.0.234-1.3.0.345" relation="incl-excl" />
    </AddinRequirement>
    <!--
      The markup is easy here.
      The AddinRequirement node may be emtpy (have no XML content) or may contain VERSION RULES.
      It must have a "name" attribute containing the name of the required add-in
      It is used by the vAddins Packager (gives serious warnings if the condition(s) are not met) and by the builder to determine whether the add-in should be enabled.
      Can also be used by the host.
      
        The "Rule" node inside an Addin Requirement tells the vAddins engine how to check for the required add-in.
        The "version" attribute is optional. It is used to check for the version according to the "relation" attribute value.
          Cannot coexist with "range".
        It must be a valid System.Version (string) or else it will throw a format exception.
        The "relation" attribute is optional. The default is "==".
          It determines how to check for the add-in version.
          It represents the operator used to verify the version!
          Any other value will result in a format exception!
        
        The "range" attribute determines a range of versions.
        It is used to show a range
          
      Multiple rules can be passed
      -->
  </Requirements>
</vAddin>

<!--
  Now you might be wondering "What's up with all these restrictions?!"
  Well, I have two good reasons:
    1. XML parsing takes a darn good amount of time. Files need to be as short as possible!
    2. Teaching discipline to amateur add-in developers. Teaching them to give all and only the asked information.
  These two things together will teach amateur add-in developers to respect the host application and the users' time.
  Users' time is the most valuable resource. The less you consume of it, the better!
-->